home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 050 / tdebugv3.arc / TDEBUG.DOC < prev   
Encoding:
Text File  |  1986-03-01  |  18.1 KB  |  657 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                              December 31, 1985
  9.  
  10.                           TDEBUG.DOC
  11.  
  12. OVERVIEW
  13.  
  14. TDEBUG is a source code debugger for use in debugging Turbo 
  15. Pascal (tm) Programs on the IBM-PC (tm).  When used in 
  16. conjunction with TURBO.COM, it allows you to:
  17.  
  18.      1.  View your source code while debugging.
  19.      2.  Trace the operation of your program statement by 
  20.          statement.
  21.      3.  Insert breakpoints in your program by procedure/function 
  22.          name or by statement number.
  23.      4.  Examine (and change) global or local variables in your 
  24.          program, including strings, array variables, and 
  25.          records.
  26.  
  27.  
  28. SYSTEM REQUIREMENTS
  29.  
  30.      1.  One of the following versions of Turbo Pascal for the 
  31.          IBM-PC:
  32.              TURBO.COM     v3.00b
  33.              TURBO.COM     v3.01a
  34.              TURBO-87.COM  v3.01a
  35.      2.  Approximately 128k more memory than would normally be 
  36.          required to run your program in the Turbo memory mode.
  37.      3.  A hard disk is desirable and may be a necessity when 
  38.          debugging large programs with the optional local 
  39.          symbols.
  40.  
  41.  
  42. OPERATION
  43.  
  44. To use TDEBUG, include the file TDEBUG.COM on the disk (or in the 
  45. directory) with TURBO.COM (or TURBO-87.COM), TURBO.MSG, and your 
  46. program file.  At the DOS prompt, call for TDEBUG.  After a brief 
  47. sign on message, TDEBUG will load TURBO.COM and transfer control 
  48. to it.  (The message 'Incorrect TURBO.COM version!' indicates 
  49. that TDEBUG and your version of TURBO.COM are incompatible.)
  50.  
  51. When calling for TDEBUG, the following optional parameters may be 
  52. used:
  53.  
  54.   G
  55.   Use global symbols only.  Users with limited disk space may 
  56.   not be able to accommodate the local symbol disk file.
  57.  
  58.   T=<filename>
  59.   The T option allows the name (and path) of the Turbo compiler 
  60.  
  61.  
  62.                            1
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.   to be specified.  '.COM' should be a part of this 
  75.   specification.  The default is TURBO.COM.
  76.  
  77.   L=<filename>
  78.   The L option allows specification of the local symbol file 
  79.   name.  This option has been included mostly to allow a path to 
  80.   be specified.  If enough space is available, a ramdisk drive is 
  81.   ideal with a hard disk being a second choice.  The default 
  82.   filename is '@@LOCAL.SYM'.
  83.  
  84.   B=n
  85.   For this option, n specifies the symbol table buffer size 
  86.   (decimal).  This is important mainly when using local symbols 
  87.   because the local symbol file size will be approximately n 
  88.   times the number of procedures and functions in the program 
  89.   under test.  Users with limited disk space will probably want 
  90.   to make n as small as possible.  Unfortunately, the actual size 
  91.   required is not known until the program under test is compiled 
  92.   so some experimenting may be necessary.  The default value is 
  93.   6000 bytes. n may not be made less than 1000 bytes.
  94.  
  95. Examples:
  96.  
  97.   TDEBUG T=TURBO-87.COM L=D:LOCAL  B=5000
  98.   TDEBUG  G
  99.  
  100.  
  101. Once TDEBUG has loaded and begun execution of TURBO.COM, all of 
  102. the commands and features of Turbo Pascal should operate as they 
  103. always have with the exception of the Run command.  The only 
  104. special requirement for programs to be debugged is that the {$U+} 
  105. compiler directive not be used.  When the Run command is 
  106. executed, TDEBUG will regain control and the debugging screen 
  107. will appear.
  108.  
  109. The debugging screen is divided into two parts.  The lower 
  110. section is the command and data section.  The '*' is a prompt for 
  111. one of the commands described later.  The top part of the screen 
  112. displays the program source code text which at this point will be 
  113. centered at the first executable statement of your program.
  114.  
  115. Within the text part of the display, the current statement (the 
  116. next one to be executed) will be highlighted.  The left margin 
  117. contains the statement number of the first statement occurring on 
  118. that particular line.  Statement numbers are consecutive numbers 
  119. and are used to refer to individual statements in the commands 
  120. described later.  Since there may be more than one statement on a 
  121. line, the statement number in the margin is that of the first 
  122. statement on the line.  The first character of each statement is 
  123. highlighted.  Note also that there may be no statements on a 
  124. given line so those lines will have no numbers.
  125.  
  126.  
  127.  
  128.                            2
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140. Dividing the two portions of the debugging screen is a line which 
  141. at this point will probably display 'Memory'.  This indicates 
  142. that the text file being observed is in memory.  Later, when 
  143. viewing a portion of the program source code which is in an 
  144. 'include' file, the name of the 'include' file will appear here.
  145.  
  146. When the Run command is issued after a fresh compilation, TDEBUG 
  147. will issue a report giving the symbol table buffer size actually 
  148. required, the number of statements and include files found and 
  149. any disk errors which might have occurred during compilation.  In 
  150. the event of any errors, it will not be possible to continue with 
  151. the debugging session until the errors are corrected.  Hit any 
  152. key to return to TURBO to make the corrections.  The most likely 
  153. error is a symbol table buffer overflow which will require a 
  154. change in the 'B' option at load time.
  155.  
  156.  
  157. SPECIAL KEYS FOR VIEWING TEXT
  158.  
  159. The following keys may be used to change the text being 
  160. displayed:
  161.  
  162.      Pg Up
  163.      Pg Dn  Move the display up or down one page.
  164.  
  165.      ^Pg Up
  166.      ^Pg Dn Move to the start or end of the current file.
  167.  
  168.      Up arrow
  169.      Down arrow  Scroll up or down one line.
  170.  
  171.      F10 key  Toggle between the debug screen and the screen
  172.               of the program under test.
  173.  
  174. In addition, the text being displayed may be changed using the 
  175. View command described later.
  176.  
  177.  
  178. COMMAND EDITOR
  179.  
  180. When entering commands, the following keys may used to edit the 
  181. command:  (They perform the same functions as they do in the 
  182. Turbo Pascal editor.)
  183.  
  184.      ^A,^S,^D,^F,^G,^T,^H,LFARW,RTARW,^LFARW,^RTARW,
  185.      Ins, Del, Backspace
  186.  
  187. The Insert mode (default) is indicated by a slightly fatter 
  188. cursor while the cursor is normal in the Overwrite mode.
  189.  
  190. In addition, the F3 function key causes the last command entered 
  191. (having more than three characters) to be redisplayed.  This may 
  192.  
  193.  
  194.                            3
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206. be used to make minor changes to a previous command or to correct 
  207. a syntax error.
  208.  
  209. Note that commands are not acted upon until the Enter key is hit.  
  210. (The cursor does not have to be at the line end to enter the 
  211. command.)
  212.  
  213.  
  214. COMMAND PARAMETERS
  215.  
  216. Commands consist of one or two letters which may be followed by 
  217. one or more parameters.  A non alphabetic character must follow 
  218. the command to delimit it from a following parameter.  The 
  219. parameters which may be used are:
  220.  
  221.   <Symbol>
  222.      A Pascal source code symbol representing a 
  223.      procedure/function name, variable, or constant as 
  224.      appropriate.  The special symbol 'RTN' may be used to refer 
  225.      to the return point of a procedure/function.  The usage of 
  226.      global or local symbols is explained more fully in a later 
  227.      section.
  228.  
  229.   <Statement>
  230.      A statement number as displayed in the left margin of the 
  231.      text display.
  232.  
  233.  
  234. COMMANDS
  235.  
  236. G    (Go)
  237.  
  238.   Format:
  239.      G [<parameter> [<parameter..]]
  240.  
  241.   The Go command starts execution of the program under test.  
  242.   Execution will continue until a breakpoint is reached, the 
  243.   program terminates, or the <control Break> key is hit.
  244.  
  245.   One or more breakpoints may be entered with the Go command.  
  246.   These breakpoints are called temporary breakpoints as they are 
  247.   in effect only until the first stopping point is reached.  Any 
  248.   temporary breakpoint would then have to reentered with the next 
  249.   Go command if desired.
  250.  
  251.   The program under test may be interrupted using the <control 
  252.   Break> key.  Note that <control C> does not perform the same 
  253.   function but rather performs its normal Turbo Pascal function 
  254.   (as defined by the {$C } compiler directive.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                            4
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.   Examples:
  273.  
  274.      G   Start execution with no temporary breakpoints. (There 
  275.          might be some permanent breakpoints, however.)
  276.  
  277.      G 345 PROC1 RTN
  278.          Start execution with temporary breakpoints at statement 
  279.          345, at the start of procedure PROC1, and at the return 
  280.          point of the current procedure/function.  In addition, 
  281.          there might be other permanent breakpoints in effect.
  282.  
  283. T    (Trace)
  284.  
  285.   Format:
  286.      T
  287.  
  288.   Execute the current statement.  Only one statement is executed.
  289.  
  290.  
  291. N    (Next)
  292.  
  293.   Format:
  294.      N
  295.  
  296.   Execute the current statement in its entirety.
  297.  
  298.   The difference between the Trace and the Next command is that 
  299.   if the current statement is a procedure or function call, Next 
  300.   will completely execute the procedure/function whereas Trace 
  301.   will Trace through the procedure/function.
  302.  
  303.  
  304. P    (Permanent breakpoint)
  305.  
  306.   Format:
  307.      [-]P [<parameter>]
  308.  
  309.   The P command is used to specify permanent breakpoints.  Unlike 
  310.   temporary breakpoints, permanent breakpoints remain in effect 
  311.   until removed (using a '-' preceding the P command).  
  312.  
  313.   If no parameter is entered, the breakpoints in effect are 
  314.   listed.
  315.  
  316.   Examples:
  317.  
  318.      P        List all permanent breakpoints.
  319.     -P        Delete all permanent breakpoints.
  320.      P 345    Install a breakpoints at statement 345.
  321.     -P PROC1  Remove a breakpoint at procedure PROC1.
  322.  
  323.  
  324.  
  325.  
  326.                            5
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338. V    (View text)
  339.  
  340.   Format:
  341.      V [<parameter>]
  342.  
  343.   The View command may be used to change the text being observed 
  344.   in the text window.  If no parameter is entered, the text will 
  345.   be centered around the current statement (the one to be 
  346.   executed next).
  347.  
  348.   Examples:
  349.  
  350.      V InitScreens   View text at procedure InitScreens.
  351.      V 545           View text around statement 545.
  352.      V Rtn           Find out where this procedure/function was
  353.                      called from.
  354.  
  355.  
  356. E    (Examine/change variable or constant)
  357.  
  358.   Format:
  359.      E <symbol>
  360.  
  361.   The Examine/change command allows the the value of global 
  362.   and local variables and constants to be displayed.  In 
  363.   addition, for variables, a new value may be entered.  Note that 
  364.   Turbo Pascal 'typed constants' are actually initialized 
  365.   variables and these may also be changed.  
  366.  
  367.   After a variable value has been output in response to the 
  368.   Examine/change command, a new value may be entered followed by 
  369.   the Enter key.  For byte and integer types, a hex value may be 
  370.   specified by preceding it with a '$'.  Hitting the Enter key 
  371.   only retains the old variable value.  
  372.  
  373.   8 bit variables (byte, char, boolean) are displayed in decimal, 
  374.   hex, and character (if printable).  In the case of boolean, 0 
  375.   is false, and 1 is true.
  376.  
  377.   Integer variables are displayed in both decimal and hex.
  378.  
  379.   Real variables are displayed in 'E' format and also decimal 
  380.   format if within a reasonable range.
  381.  
  382.   Pointer variables are displayed with the phrase 'Points to:' 
  383.   followed by an address and symbolic name if appropriate.  If 
  384.   the pointer variable is followed by '^', the contents of the 
  385.   pointed to variable are displayed.  To change a pointer 
  386.   variable, use either a symbolic name or a segment:offset 
  387.   numerical address with a colon separator such as $1234:$5678.
  388.  
  389.  
  390.  
  391.  
  392.                            6
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.   String variables are displayed as a string within quotes.  When 
  405.   specifying a change to a string variable, the new string should 
  406.   be enclosed in quotes.  A null string is specified by two 
  407.   quotes enclosing nothing.  Individual characters of a string 
  408.   may be displayed and changed by treating the string as an 
  409.   array.
  410.  
  411.   Non numerical scaler variables are displayed numerically.  For 
  412.   instance, a variable defined as
  413.  
  414.     Var   Color   :(red,green,blue,orange);
  415.  
  416.   would be be given a value of 2 if it contained blue.  However, 
  417.   note that:
  418.  
  419.      E BLUE
  420.  
  421.   could be used to verify that blue was represented by 2.
  422.  
  423.   Sets cannot be examined.
  424.  
  425.   Examples:
  426.  
  427.      E RealArray[4,3]
  428.      E InString
  429.      E PersonRecord[12].ID.Lastname
  430.      E PT^.Index1
  431.      E START^.NEXT^.NEXT^.NEXT^.VALUE[10][3]
  432.  
  433.  
  434. Q    (Quit)
  435.  
  436.   Format:
  437.      Q
  438.  
  439.   The Quit command when entered in TDEBUG returns control to 
  440.   Turbo Pascal without running the program under test to 
  441.   completion.
  442.  
  443.  
  444. X    (Translate)
  445.  
  446.   Format:
  447.      X <parameter>
  448.  
  449.   The translate command translates symbols and statements into 
  450.   segment-offset addresses.  This is useful mainly when using an 
  451.   external assembly language debugger.  Unlike the E (Examine) 
  452.   command, a variable need not be completely specified to get an 
  453.   address.
  454.  
  455.  
  456.  
  457.  
  458.                            7
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.   Examples:
  471.  
  472.      X PersonRecord              ;yields the first address of 
  473.                                   PersonRecord
  474.      X PersonRecord[12]          ;yields the first address of 
  475.                                   PersonRecord[12]
  476.      X PersonRecord[12].ID       ;yields the first address of 
  477.                                   PersonRecord[12].ID
  478.  
  479.  
  480. DB   (DeBug)
  481.  
  482.   Format:
  483.      DB
  484.  
  485. This command is used to enter an optional external assembly 
  486. language debugger.  Its use is explained in a later section.
  487.  
  488.  
  489. SYMBOLS
  490.  
  491. TDEBUG makes use of two sets of symbols, the global symbols and 
  492. (optionally) the local symbols.  Global symbols are those which 
  493. would be available in the main block of the Pascal program and 
  494. include all non nested procedure/function names as well as 
  495. variables and constants defined outside of procedure/functions.
  496.  
  497. Local symbols are those defined within a procedure/function and 
  498. are valid and only accessible within the block of that 
  499. procedure/function.  Local symbols include the formal parameters 
  500. defined in the procedure heading and also function results.  Note 
  501. that the block boundaries are delimited by the BEGIN and END for 
  502. any particular procedure.  In particular, this means that local 
  503. symbols cannot be accessed when the current instruction is a 
  504. procedure/function heading.  This should be kept in mind since 
  505. breakpoints are frequently placed at procedure/function headings.
  506.  
  507. Error messages such as 'Not a GLOBAL symbol' or 'Not a GLOBAL 
  508. Variable' are meant to be a reminder that only the GLOBAL symbols 
  509. are being searched.  From a procedure/function heading it is only 
  510. necessary to do one 'T' (Trace) command to be within procedure 
  511. block where the local symbols can be accessed.
  512.  
  513. TDEBUG searches local symbols before global symbols.  This is of 
  514. significance in cases where duplicate symbol names are used.
  515.  
  516.  
  517. HINTS
  518.  
  519. It is possible to insert breakpoints in the source code using 
  520. INLINE($CC).  These breakpoints cannot be removed by TDEBUG 
  521. but may be useful for conditional breaks.  For instance:
  522.  
  523.  
  524.                            8
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.   IF I=49 THEN INLINE($CC);
  538.  
  539.  
  540. USING AN EXTERNAL ASSEMBLY LANGUAGE DEBUGGER
  541.  
  542. It is possible to use an assembly language debugger in 
  543. conjunction with TDEBUG.  It is often desirable to examine the 
  544. compiled code of a program to determine what the problems really 
  545. are and this provides a convenient way to do this.  The following 
  546. instructions are for using DOS DEBUG although other debuggers may 
  547. be used in a similar manner.
  548.  
  549. Load DEBUG by:
  550.  
  551.   DEBUG  TDEBUG.COM <parameters>
  552.  
  553. where the <parameters> are the optional TDEBUG parameters.  Once 
  554. the load is completed and you are in DEBUG, issue the 'G' (Go) 
  555. command.  Operation of TDEBUG and TURBO will proceed in a normal 
  556. fashion.  At the appropriate time in the debugging session, use 
  557. the X (Translate) command to find the machine addresses to be 
  558. inspected.  Then issue the DB (DeBug) command.  You will find 
  559. yourself back in DEBUG.
  560.  
  561. At this point, the DEBUG U (Unassemble) or D (Display) commands 
  562. can be used to inspect code or data.  
  563.  
  564. To reenter TDEBUG, it is necessary to jump over the INT 3 
  565. instruction which caused the break to DEBUG.  Do this by using 
  566. the G command:
  567.  
  568.   G=xxxx
  569.  
  570. where xxxx is the contents of the IP register plus 1.  No 
  571. breakpoints should be installed with DEBUG as TDEBUG takes over 
  572. the breakpoint vector when it is reentered.
  573.  
  574.  
  575. RESTRICTIONS, PROBLEMS, BUGS
  576.  
  577. The following are current limits.  
  578.  
  579.   Permanent and temporary breakpoints are limited to 6 each.
  580.   Maximum number of include files = 20.
  581.   Maximum include file size = 32k.
  582.   Maximum number of statements = 4000.
  583.   Maximum symbol length = 28.
  584.   Maximum number of local symbol blocks = 250.
  585.  
  586.  
  587. Presently symbolic constants cannot be used as subscripts in the
  588. Examine/change command.  For instance, if
  589.  
  590.  
  591.                            9
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  Var   Opcode  :ARRAY[MOV..CMP] OF BYTE;
  604.  
  605. it is presently necessary to specify OPCODE[0] rather than
  606. OPCODE[MOV] when using the Examine/change command.
  607.  
  608. The <control Break> program interrupt does not perform properly 
  609. when the program under test is waiting for keyboard input.
  610.  
  611. A simple screen switch is currently used.  This limits debugging
  612. to text only programs.
  613.  
  614. Function results should be accessible only within the block of 
  615. the function whereas they can now be accessed from wherever the 
  616. function may be called.  Any results displayed outside of the
  617. function block are not valid.  Use care not to alter a function 
  618. result outside of its block as you will be altering an odd memory 
  619. location.
  620.  
  621. Variables defined as 'absolute' are sometimes stored as pointers.  
  622. TDEBUG presently does not resolve these correctly.
  623.  
  624. There is a problem when compiling to a disk COM file.  Turbo 
  625. often takes a short cut and transfers directly from memory to 
  626. disk without recompiling.  However, the memory file has been 
  627. altered by TDEBUG and the resulting COM file is corrupted.  It 
  628. is best at this stage to compile to disk only without the 
  629. debugger.
  630.  
  631.  
  632.  
  633.  
  634.  
  635.      IBM-PC is a trademark of International Business Machines 
  636.      Corporation.
  637.      Turbo Pascal is a trademark of Borland International Inc.
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.                           10
  657.